Excel 加载项教程

在本教程中，将创建 Excel 任务窗格加载项，该加载项将：

提示

如果已使用 Yeoman 生成器完成了“创建 Excel 任务窗格加载项”快速入门，并希望使用此项目作为该教程的起点，直接转至“创建表”以开始此教程。

如果需要本教程的完整版本，请转到 GitHub 上的 Office 外接程序示例存储库。

Node.js（最新LTS 版本）。 访问 Node.js 站点 ，下载并安装适合你的操作系统的版本。

最新版本的 Yeoman 和适用于 Office 加载项的 Yeoman 生成器。若要全局安装这些工具，请从命令提示符处运行以下命令。

注意

即便先前已安装了 Yeoman 生成器，我们还是建议你通过 npm 将包更新为最新版本。

已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

注意

如果你还没有 Office，可以加入 Microsoft 365 开发人员计划以免费获得为期 90 天的可续订 Microsoft 365 订阅，以便在开发期间使用。

已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

注意

如果你还没有 Office，可以加入 Microsoft 365 开发人员计划以免费获得为期 90 天的可续订 Microsoft 365 订阅，以便在开发期间使用。

运行以下命令，使用 Yeoman 生成器创建加载项项目。

注意

运行该yo office命令时，可能会收到有关 Yeoman 和 Office 加载项 CLI 工具的数据收集策略的提示。 根据你的需要，使用提供的信息来响应提示。

出现提示时，请提供以下信息以创建加载项项目。

完成此向导后，生成器会创建项目，并安装支持的 Node 组件。 如果在初始设置过程中出现问题，可能需要在项目的根文件夹中手动运行 npm install 。

注意

如果使用 Node.js 20.0.0 或更高版本，则当生成器运行安装时，可能会看到一条警告，指出你的引擎不受支持。 我们正在努力解决此问题。 同时，警告不会影响生成的生成器或项目，因此可以忽略它。

提示

创建加载项项目后，可忽略 Yeoman 生成器提供的后续步骤指南。 本文中的分步说明提供了完成本教程所需的全部指南。

本教程的这一步是，以编程方式测试加载项是否支持用户的当前版本 Excel，向工作表中添加表格，使用数据填充表格，并设置格式。

在代码编辑器中打开项目。

打开 ./src/taskpane/taskpane.html 文件。 此文件含有任务窗格的 HTML 标记。

找到 元素并删除在开始 标记后和关闭 标记前出现的所有行。

打开 标记后立即添加下列标记：

打开 ./src/taskpane/taskpane.js 文件。 此文件包含用于加快任务窗格与 Office 客户端应用程序之间的交互的 Office JavaScript API 代码。

执行以下操作，删除对 run 按钮和 run() 函数的所有引用：

查找并删除行 document.getElementById("run").onclick = run;。

查找并删除整个 run() 函数。

在 Office.onReady 函数调用中，找到行 if (info.host === Office.HostType.Excel) { 并紧跟该行添加下列代码。 注意：

将以下函数添加到文件末尾。 注意：

Excel.js 业务逻辑将添加到传递给 Excel.run 的函数。 此逻辑不立即执行。 相反，它会被添加到挂起的命令队列中。

context.sync 方法将所有已排入队列的命令发送到 Excel 以供执行。

通过 tryCatch 任务窗格与工作簿交互的所有函数都将使用该函数。 以这种方式捕获 Office JavaScript 错误是一种通用处理任何未捕获的错误的便捷方法。

注意

以下代码使用 ES6 JavaScript，与 旧版 Office 不兼容，后者使用 Trident (Internet Explorer 11) 浏览器引擎。 有关如何在生产环境中支持这些平台的信息，请参阅 支持较旧的 Microsoft Webviews 和 Office 版本。 加入 Microsoft 365 开发人员计划，以免费获得为期 90 天的可续订 Microsoft 365 订阅以及最新的 Office 应用程序，以便在开发期间使用。

在 createTable() 函数中，将 TODO1 替换为以下代码。 注意：

该代码使用 add 工作表的表集合的 方法创建一个表，即使它为空，该集合也始终存在。 这是创建 Excel.js 对象的标准方式。 没有类构造函数 API，切勿使用 new 运算符创建 Excel 对象。 相反，请添加到父集合对象。

add 方法的第一个参数仅是表格最上面一行的范围，而不是表格最终使用的整个范围。 这是因为当加载项填充数据行时（在下一步中），它将新行添加到表中，而不是将值写入现有行的单元格。 这是一种常见模式，因为在创建表时，表将具有的行数通常未知。

表名称必须在整个工作簿中都是唯一的，而不仅仅是在工作表一级。

在 createTable() 函数中，将 TODO2 替换为以下代码。 注意：

范围的单元格值是通过一组数组进行设置。

表格中的新行是通过调用表格的行集合的 add 方法进行创建。 通过在作为第二个参数传递的父数组中添加多个单元格值数组，可以在一次 add 调用中添加多个行。

在 createTable() 函数中，将 TODO3 替换为以下代码。 注意：

此代码将从零开始编制的索引传递给表格的列集合的 getItemAt 方法，以获取对“金额”列的引用。

注意

Excel.js 集合对象（如 TableCollection、WorksheetCollection 和 TableColumnCollection）有 items 属性，此属性是子对象类型的数组（如 Table、Worksheet 或 TableColumn），但 *Collection 对象本身并不是数组。

然后，此代码将“金额”列的范围格式化为欧元（精确到小数点后两位）。 在数字格式代码一文中详细了解 Excel 数字格式语法/

最后，它确保了列宽和行高足以容纳最长（或最高）的数据项。 请注意，此代码必须获取要格式化的 Range 对象。 TableColumn 和 TableRow 对象没有格式属性。

验证是否已保存了对项目所做的所有更改。

完成以下步骤，以启动本地 Web 服务器并旁加载你的加载项。

注意

即使在开发过程中，Office 外接程序也应使用 HTTPS，而不是 HTTP。 如果在运行以下命令之一后系统提示安装证书，请接受安装 Yeoman 生成器提供的证书的提示。 你可能还必须以管理员身份运行命令提示符或终端才能进行更改。

提示

如果在 Mac 上测试加载项，请先运行项目根目录中的以下命令，然后再继续。 运行此命令时，本地 Web 服务器将启动。

若要在 Excel 中测试加载项，请在项目的根目录中运行以下命令。 这将启动本地的 Web 服务器 (如果尚未运行的话), 并使用加载的加载项打开 Excel。

若要在 Excel 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将 "{url}" 替换为你拥有权限的 OneDrive 或 SharePoint 库上 Excel 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

在 Excel 中，选择“ 开始 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮以打开加载项任务窗格。

在任务窗格中，选择“创建表”按钮。

本教程的这一步是，筛选并排序之前创建的表。

打开 ./src/taskpane/taskpane.html 文件。

查找create-table按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 create-table 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 filterTable() 函数中，将 TODO1 替换为以下代码。 注意：

代码先将列名称传递给 getItem 方法（而不是像 getItemAt 方法一样将列索引传递给 createTable 方法），获取对需要筛选的列的引用。 由于用户可以移动表格列，因此给定索引处的列可能会在表格创建后更改。 所以，更安全的做法是，使用列名称获取对列的引用。 上一教程安全地使用了 getItemAt，因为是在与创建表格完全相同的方法中使用了它，所以用户没有机会移动列。

applyValuesFilter 方法是对 Filter 对象执行的多种筛选方法之一。

打开 ./src/taskpane/taskpane.html 文件。

查找filter-table按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 filter-table 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 sortTable() 函数中，将 TODO1 替换为以下代码。 注意：

此代码创建一组 SortField 对象，其中只有一个成员，因为加载项只对“商家”列进行了排序。

SortField 对象的 key 属性是用于排序的列的从零开始编制索引。 表中的行按照所引用列中的值进行排序。

Table 的 sort 成员是 TableSort 对象，并不是方法。 SortField 传递到 TableSort 对象的 apply 方法。

验证是否已保存了对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Excel 中，请继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项：

若要在 Excel 中测试加载项，请在项目的根目录中运行以下命令。 这将启动本地的 Web 服务器 (如果尚未运行的话), 并使用加载的加载项打开 Excel。

若要在 Excel 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将 "{url}" 替换为你拥有权限的 OneDrive 或 SharePoint 库上 Excel 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在 Excel 中打开，请转到“ 开始 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮将其打开。

如果之前在此教程中添加的表格未在打开的工作表中出现，选择任务窗格中的“创建表”按钮。

选择“筛选表”按钮和“排序表”按钮（按顺序和倒序中的任一顺序排序皆可）。

本教程的这一步是，使用先前创建的表中的数据创建图表，再设置图表格式。

打开 ./src/taskpane/taskpane.html 文件。

查找sort-table按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 sort-table 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 createChart() 函数中，将 TODO1 替换为以下代码。 请注意，为了排除标题行，此代码使用 Table.getDataBodyRange 方法（而不是 getRange 方法），获取要绘制成图表的数据的范围。

在 createChart() 函数中，将 TODO2 替换为以下代码。 请注意以下参数。

add 方法的第一个参数指定图表类型。 有几十种类型。

第二个参数指定要在图表中添加的数据的范围。

第三个参数确定是按行方向还是按列方向绘制表格中的一系列数据点。 选项 auto 指示 Excel 确定最佳方法。

在 createChart() 函数中，将 TODO3 替换为以下代码。 此代码的大部分内容非常直观明了。 请注意几下几点：

setPosition 方法的参数指定应包含图表的工作表区域的左上角和右下角单元格。 Excel 可以调整行宽等设置，以便图表能够适应所提供的空间。

“系列”是指表格列中的一组数据点。 因为表格中只有一个非字符串列，所以 Excel 推断此列就是要绘制成图表的唯一一列数据点。 它将其他列解释为图表标签。 因此，图表中只有一个系列，它的索引为 0。 这是要标记为“金额（欧元）”的系列。

验证是否已保存了对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Excel 中，请继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项：

若要在 Excel 中测试加载项，请在项目的根目录中运行以下命令。 这将启动本地的 Web 服务器 (如果尚未运行的话), 并使用加载的加载项打开 Excel。

若要在 Excel 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将 "{url}" 替换为你拥有权限的 OneDrive 或 SharePoint 库上 Excel 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在 Excel 中打开，请转到“ 开始 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮将其打开。

如果之前在此教程中添加的表格未在打开的工作表中出现，选择任务窗格中的“创建表”按钮，随后选择“筛选表”按钮和“排序表”按钮（按顺序和倒序中的任一顺序排序皆可）。

选择“创建图表”**** 按钮。 此时，图表创建完成，其中仅包含筛选出的行中的数据。 底部数据点上的标签按图表的排序顺序进行排序，即按商家名称的字母倒序排序。

如果表格很长，导致用户必须滚动才能看到一些行，那么标题行可能会在滚动时不可见。 本教程的这一步是，冻结以前创建的表格的标题行，让它在用户向下滚动工作表时依然可见。

打开 ./src/taskpane/taskpane.html 文件。

查找create-chart按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 create-chart 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 freezeHeader() 函数中，将 TODO1 替换为以下代码。 注意：

Worksheet.freezePanes 集合是工作表中的一组窗格，在工作表滚动时就地固定或冻结。

freezeRows 方法需要使用要就地固定的行数（自顶部算起）作为参数。 传递 1 以就地固定第一行。

验证是否已保存了对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Excel 中，请继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项：

若要在 Excel 中测试加载项，请在项目的根目录中运行以下命令。 这将启动本地的 Web 服务器 (如果尚未运行的话), 并使用加载的加载项打开 Excel。

若要在 Excel 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将 "{url}" 替换为你拥有权限的 OneDrive 或 SharePoint 库上 Excel 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在 Excel 中打开，请转到“ 开始 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮将其打开。

如果之前在此教程中添加的表格出现在此工作表中，将其删除。

在任务窗格中，选择“创建表”按钮。

在任务窗格中，选择“冻结标题”按钮。

尽量向下滚动工作表，直到在上面的行不可见时表格标题在顶部依然可见。

在此教程的此步骤中，将向功能区添加一个按钮，以打开和关闭工作表保护。

打开清单文件 ./manifest.xml。

找到 元素。 此元素定义了“主页”功能区上一直用于启动加载项的“显示任务窗格”按钮。 将向“主页”功能区上的相同组添加第二个按钮。 在结束 标记和结束 标记之间，添加以下标记。